Per OpenAPI spec, sibling keywords alongside $ref are version-dependent. For v2/v3.0 all siblings must be dropped; for v3.1/v3.2 schema refs, peer keywords including extensions are allowed; for v3.1/v3.2 non-schema refs, only summary and description are permitted. This PR addresses the gap in extension support for schema references.

Description

OpenApiSchemaReference correctly drops sibling keywords (description, title, etc.) for v2/v3.0 serialization, but lacked support for serializing/deserializing extension properties (x-*) alongside $ref in v3.1/v3.2, and was missing a SerializeAsV32 override with loop detection.

Type of Change

• New feature (non-breaking change which adds functionality)

Related Issue(s)

Changes Made

JsonSchemaReference

• Added Extensions property (IDictionary<string, IOpenApiExtension>?) — serialized only in v3.1/v3.2, silently dropped for v2/v3.0
• Updated copy constructor to copy extensions
• SerializeAdditionalV3XProperties now calls writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_1)
• SetAdditional31MetadataFromMapNode now parses x-* properties from $ref sibling keywords into Extensions

OpenApiSchemaReference

• Extensions upgraded from getter-only (Target?.Extensions) to get/set — reference-level extensions take priority over target
• Added SerializeAsV32 override with loop detection (matches existing SerializeAsV31 pattern)

PublicAPI.Unshipped.txt

• Registered: JsonSchemaReference.Extensions (get/set), OpenApiSchemaReference.Extensions.set, OpenApiSchemaReference.SerializeAsV32

Tests

• Updated SerializeSchemaReferenceAsV31JsonWorks to include an extension; updated verified snapshots
• Added SerializeSchemaReferenceAsV32JsonWorks + snapshots
• Added ParseSchemaReferenceWithExtensionsWorks — parses x-* from a v3.1 $ref node
• Added SchemaReferenceExtensionsNotWrittenInV30 / SchemaReferenceExtensionsNotWrittenInV2 — asserts only $ref is emitted

// v3.1: extensions written alongside $ref
var schemaRef = new OpenApiSchemaReference("Pet", doc)
{
    Description = "Overridden description",
    Extensions = new Dictionary<string, IOpenApiExtension>
    {
        ["x-custom"] = new JsonNodeExtension(JsonValue.Create("value"))
    }
};
// Serializes as: { "description": "...", "x-custom": "value", "$ref": "#/components/schemas/Pet" }

// v3.0: ONLY $ref emitted — description and extensions silently dropped
// { "$ref": "#/components/schemas/Pet" }

Testing

• Unit tests added/updated
• All existing tests pass

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Versions applicability

• My change applies to the version 1.X of the library, if so PR link:
• My change applies to the version 2.X of the library, if so PR link:
• My change applies to the version 3.X of the library, if so PR link:
• I have evaluated the applicability of my change against the other versions above.

Additional Notes

Extension support is intentionally scoped to JsonSchemaReference (schema refs only). Non-schema reference objects (OpenApiReferenceWithDescription, OpenApiReferenceWithDescriptionAndSummary) remain extension-free per the v3.1 Reference Object spec, which explicitly prohibits additional properties.

using System;
using System.IO;
using Microsoft.OpenApi.Models;
using Microsoft.OpenApi.Writers;

class Program
{
    static void Main()
    {
        var document = new OpenApiDocument
        {
            Info = new OpenApiInfo
            {
                Title = "Ref Description Test",
                Version = "1.0.0"
            },

            Components = new OpenApiComponents
            {
                Schemas =
                {
                    ["Pet"] = new OpenApiSchema
                    {
                        Type = "object",
                        Properties =
                        {
                            ["name"] = new OpenApiSchema { Type = "string" }
                        }
                    }
                }
            },

            Paths = new OpenApiPaths
            {
                ["/test"] = new OpenApiPathItem
                {
                    Operations =
                    {
                        [OperationType.Get] = new OpenApiOperation
                        {
                            Responses =
                            {
                                ["200"] = new OpenApiResponse
                                {
                                    Description = "OK",
                                    Content =
                                    {
                                        ["application/json"] = new OpenApiMediaType
                                        {
                                            Schema = new OpenApiSchemaReference("Pet")
                                            {
                                                Description = "Local description"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        };

        using var stream = new MemoryStream();
        using var writer = new OpenApiJsonWriter(new StreamWriter(stream));

        document.SerializeAsV3(writer);
        writer.Flush();

        stream.Position = 0;
        Console.WriteLine(new StreamReader(stream).ReadToEnd());
    }
}

$ref: '#/components/schemas/Pet'
description: Local description

allOf:
  - $ref: '#/components/schemas/Pet'
description: Local description

• Fixes OpenApiSchemaReference allows Description alongside $ref producing non-spec-compliant output in OAS 3.0 (clone of #2745) #2763

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.